home *** CD-ROM | disk | FTP | other *** search
/ Scene 96 / Scene 96 International Edition (Zyklop Software) (Disc 2) (1997).iso / misc / coding / ct_xmp15 / mxmplay.doc < prev    next >
Text File  |  1996-09-15  |  17KB  |  493 lines
  1.  
  2.                                      ▄▄
  3.                      ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ ██ ▄▄▄ ▄▄ ▄▄▄▄▄▄▄▄
  4.                         ▄▄▄▄▄ ▄▄  ▄▄ ██▄▄▄  ▄▄  ▄▄▄▄▄ tm
  5.                        ██     ██  ██ ██  ██ ██ ██
  6.                        ██     ██  ██ ██  ██ ██ ██
  7.                         ▀▀▀▀▀  ▀▀▀▀▀ ▀▀▀▀▀  ▀▀  ▀▀▀▀▀
  8.                      ▀▀▀▀ tiny gus xm player  v1.5 ▀▀▀▀
  9.  
  10.  
  11.  
  12.     Legal disclaimer:
  13. ==============================================================================
  14.  
  15.   You may copy this package without restrictions as long as no
  16.   money is charged for copying and it is passed on unmodified with
  17.   all its files:
  18.     MXMPLAY.DOC           (this file)
  19.     FILE_ID.DIZ           (fileid)
  20.     MXMPLAY.ASM           (the player source)
  21.     MXMPLAY.H             (include file for c/c++)
  22.     MXMPLAY.INC           (include file for asm)
  23.     MXMALLFX.INC          (all effects include file for mxmplay.asm)
  24.     MXMPLAY.OBJ           (compiled player object)
  25.     XM2MXM.CPP            (the conversion source)
  26.     XM2MXM.EXE            (the conversion program)
  27.     CPPEXAM.CPP           (example for WC++)
  28.     MXMPLAY.EXE           (compiled C++ example, plays .MXM files)
  29.     MAKEFILE.             (makefile for wmake)
  30.     ATOMIC.INC            (asm include song dump for examples)
  31.     ???EXAM.ASM           (asm-example for supported systems)
  32.     ???MAKE.BAT           (make files for asm-examples)
  33.     ATOMIC.XM             (original song by Screamager)
  34.  
  35.   The package is delivered as is. The author does not guarantee to
  36.   make further versions or bugfixes. The author cannot be made liable for
  37.   damage or data loss this piece of code causes, use it at your own risk.
  38.  
  39.   You may use MXMPLAY in your productions if:
  40.     -you credit me for the player while runtime or in an info file.
  41.     -no money is charged for your production.
  42.  
  43.   You may not use MXMPLAY if:
  44.     -you belong to Complex and not include the copyright notice
  45.      (copyright db "...") in your next production TWICE... :)
  46.  
  47.   You may modify the source for your productions, (see Introduction!)
  48.   but don't remove the copyright message or you'll lose the right to
  49.   use mxmplay.
  50.  
  51.  
  52.  
  53.  
  54.     Introduction
  55. ==============================================================================
  56.  
  57.   This is a MOD and XM player package for the GUS in flat mode.
  58.   It was optimized for size not for speed. The size is about 5.6k or 3.8k
  59.   if you pack it with PMWLITE, but the size can be reduced by excluding
  60.   unused effects. It was designed for the compo version of 64k intros,
  61.   originally for the Lasse Reinb0ng Intro by cubic team & $een presented at
  62.   the Party 5 held in the end of December'95 in Fredericia/Denmark.
  63.   It supports nearly all XM effects and features. You can also play S3Ms,
  64.   but the player will only play what FastTracker II makes of it.
  65.   It supports the GUS and no device.
  66.   It supports at least DOS/4G(W), PMODE/W, DOS32 and EOS. It will also work
  67.   with PMODE if you set up a flat memory model (see section MXMPLAY.ASM...)
  68.   or make "gates" to the functions, that make a temporary flat model
  69.   (flat stack and flat code, ie: cs=ds=es=ss).
  70.   It supplies timer and music syncronisation functions for your production.
  71.  
  72.   If you find any incompatibilities with FT2 please tell me.
  73.  
  74.   Please ONLY use MXMPLAY if the size of the executable matters.
  75.   If not use a real soundsystem like MIDAS!
  76.   I'd also like to encourage you to make a final version of your production
  77.   if you use a GUS-only player like MXMPLAY, because there are still so
  78.   many guys, who do not own a GUS and demos/intros without sound are soooooo
  79.   boooooooring.
  80.  
  81.   If you make changes to mxmplay to make it work with different systems or
  82.   add new features to it, please send me a copy and a *description* your
  83.   changes. I will then include it in the official package (with credits,
  84.   of course), and you don't have to change new versions.
  85.  
  86.   I am especially interested in:
  87.     -SB series support (this will give BIIIIG creds! :) )
  88.     -screen sync
  89.     -a pmode example
  90.  
  91.  
  92.  
  93.  
  94.     Revision history:
  95. ==============================================================================
  96.  
  97.   1.5: 15.9.96
  98.     -xmpInit now only accepts the GUS port
  99.     -xmpGetGUSPort gets the GUS port from an environment near ptr
  100.     -xmpGetEnvPtrDPMI gets the environment near ptr from the PSP seg
  101.     -xmpGetEnvPtrDOS32 gets the environment near ptr for DOS 32 progs
  102.     -volume fadeout is used even if volume envelope is disabled.
  103.      i'm not quite sure about it, but it seems to be like that in FT 2.05
  104.      (if not, change it back to what it was before in xm2mxm.cpp)
  105.  
  106.   1.4: 30.6.96
  107.     -defines at the top of MXMPLAY.ASM to exclude unused effects
  108.     -XM2MXM generates include files for MXMPLAY.ASM to exclude unused effects
  109.  
  110.   1.3: 10.4.96
  111.     -tremor
  112.     -set envelope position
  113.     -glissando
  114.     -if sustain is off no instrument changes are allowed
  115.     -relocation free code
  116.     -clean patterns fixed
  117.  
  118.   1.2: 30.1.96
  119.     -source included
  120.     -sample offset corrected
  121.     -volume/global volume/panning slide corrected
  122.     -starting order adjustable
  123.  
  124.   1.1: 21.12.95
  125.     -automatic gus detect, xmpInit changed
  126.     -global variable "__psp" needed for detect
  127.     -names have changed, underscores now after function names
  128.     -delta sample values for better compression
  129.     -sync now works :), thanks go to the one who told me...
  130.  
  131.   1.0:  4.12.95
  132.     -first release
  133.  
  134.  
  135.  
  136.  
  137.     The conversion program:
  138. ==============================================================================
  139.  
  140.   XM2MXM [options] source [dest]
  141.  
  142.   This program converts an XM to the internal format called MXM.
  143.   You might ask why another format, but this format shall not be used
  144.   for music interchange, it is just very easy to read and made the code
  145.   about 1k smaller.
  146.   If you want to play MODs or S3Ms you have to convert them to XM first.
  147.  
  148.   options:
  149.     -p0:   XM-panning (instruments) (default)
  150.     -p1:  MOD-panning (LRRLLRRL)
  151.     -p2:  MOD-panning (less extreme)
  152.     -p3:  S3M-panning (LRLRLRLR)
  153.     -p4:  S3M-panning (less extreme)
  154.     -p5:    0-panning (MMMMMMMM)
  155.      -d:  do not use delta value samples
  156.      -i:  generate effects include file
  157.  
  158.   If you want to play a MOD use -p1, -p2 to use correct panning.
  159.   A converted S3M would need -p3/4 if it uses standard panning, otherwise
  160.   you'd have to change the panning values in the header of the mxm.
  161.   (use -p1 and look for 00FFFF0000FFFF00...)
  162.  
  163.   If you want to reduce the size of the code, use the -i parameter
  164.   and include the generated .INC file in MXMPLAY.ASM (place is marked).
  165.   If you want to play more than one module, combine the defines in the
  166.   .INC files with OR, except the USEFREQTAB define which must be 2 if
  167.   both frequency tables are used.
  168.  
  169.  
  170.  
  171.     The MXM Format:
  172. ==============================================================================
  173.  
  174.   The MXM Format was designed to be easy to read, small, for use on a GUS
  175.   only, and to support all of FastTracker II's featues. It uses S3M like
  176.   pattern packing, so you can increase the number of channels without a
  177.   change in size (of course they would have to stay clear). The pattern
  178.   packing of XM would increase the size. The MXM format uses NO SAMPLE
  179.   PACKING, though it can use "delta values". If you want to pack the samples,
  180.   you can do so, as long as the song is passed to the xmpInit routine
  181.   unmodified. 3 dwords in the header tell you where to find the samples
  182.   and how many there are:
  183.     offset 1Ch: offset of the samples
  184.     offset 20h: number of 8 bit samples
  185.     offset 24h: number of 16 bit samples
  186.  
  187.   You will find more detailed information on the format in the source code.
  188.  
  189.  
  190.  
  191.  
  192.     Notes on the implementation of the XM format:
  193. ==============================================================================
  194.  
  195.   E5x  (finetune)                not implemented
  196.   EFx  (funk repeat???)          set sync value
  197.   Sxx  -                         set sync value
  198.  
  199.   all other commands and features should be supported correctly.
  200.   bugreports to the address listed below, please...
  201.   i prefer tiny xm test modules with the bug isolated as far as possible.
  202.   send them uuencoded, it will save me a lot of time!
  203.  
  204.  
  205.  
  206.     MXMPLAY.ASM and its functions:
  207. ==============================================================================
  208.  
  209.   At the top of MXMPLAY.ASM you find some setting you might wish to
  210.   change to reduce the size of MXMPLAY.OBJ. All the rest of the code can
  211.   stay unmodified in most cases.
  212.   With GETSETINTMODE you can set the supported irq set and get methods.
  213.   If you set DPMIPSPCODE or DOS32CODE to zero you can exclude functions
  214.   that determine the linear address of the environment.
  215.   You can replace mxmallfx.inc with an fx file generated by xm2mxm -i
  216.   which removes all code for unused fx from the object file.
  217.   EOS users should include eos.inc, but I've already included the needed
  218.   defines from v2.07 for eos.inc independence. (use /dUSEEOSINC)
  219.  
  220.   To compile MXMPLAY.ASM with TASM use the following command line:
  221.     tasm mxmplay /m /ml
  222.  
  223.   The object file was generated with TASM 3.1. It has one segment called
  224.   MXMPLAY_TEXT which is defined as dword public use32 'CODE'. It will link
  225.   to your flat mode programs without a problem.
  226.  
  227.   -all function names end with an underscore and are case sensitive
  228.   -parameters are passed in registers
  229.   -on entry to all functions CS,DS,ES,SS must point to flat memory and
  230.     the direction flag must be clear
  231.  
  232.   Watcom C/C++ coders must include mxmplay.h for correct access.
  233.   Assembler coders must include mxmplay.inc, assembly equivalents for
  234.   the C/C++ stuff are in brackets.
  235.  
  236.   Function overview:
  237.  
  238.     xmpInit
  239.     xmpPlay
  240.     xmpStop
  241.     xmpSetVolume
  242.     xmpGetSync
  243.     xmpGetPos
  244.     xmpGetTimer
  245.     xmpGetEnvPtr
  246.     xmpGetGUSPortDPMI
  247.     xmpGetGUSPortDOS32
  248.  
  249.  
  250.  
  251. xmpInit: (xmpInit_)
  252. ------------------------------------------------------------------------------
  253.   int xmpInit(void *mxmmem, unsigned long gusport, void *mxmdata,
  254.               unsigned long maxtimerrate, int getsetintmode);
  255.  
  256.   Inits the soundsystem and prepares the module for playing.
  257.  
  258.   mxmmem: (esi)
  259.     Pointer to the module. You must load the complete module from disk
  260.     and pass the address to this function.
  261.  
  262.   gusport: (eax)
  263.     Port of the GUS or 0 for no sound.
  264.  
  265.   mxmdata: (ebx)
  266.     Pointer to 16k of memory for internal use.
  267.  
  268.   maxtimerrate: (ecx)
  269.     The maximum number of clock ticks (1193046 ticks/sec) between two
  270.     irq 0 calls. Never set this to more than 65536. Set this to 65536 if
  271.     you want to have a periodically called routine. Install your interrupt
  272.     handler after starting to play and deinstall before stopping to play.
  273.     The interval between two subsequent calls to the interrupt is no longer
  274.     than this value, but will vary while runtime.
  275.  
  276.   getsetintmode: (edx)
  277.     determines which get/set irq method is to be used:
  278.       0: dpmi, works with DOS32, PMODE/W and other good dpmi servers
  279.       1: dos, works with DOS4G and PMODE/W
  280.       2: eos, works with EOS
  281.     use defines MXMINTMODE...
  282.  
  283.   returnvalue: (eax)
  284.     0: failed (at the moment only if the module signature is wrong)
  285.     1: ok
  286.  
  287.   modifies: eax ebx ecx edx esi edi
  288.  
  289.  
  290.  
  291. xmpPlay: (xmpPlay_)
  292. ------------------------------------------------------------------------------
  293.   void xmpPlay(unsigned int startord);
  294.  
  295.   Enables the timer services and starts to play the module.
  296.  
  297.   startord: (eax)
  298.     start playing at this order
  299.  
  300.   modifies: eax ebx ecx edx esi edi
  301.  
  302.  
  303.  
  304. xmpStop: (xmpStop_)
  305. ------------------------------------------------------------------------------
  306.   void xmpStop();
  307.  
  308.   Stop the sound output and disables the timer services.
  309.  
  310.   modifies: eax ebx ecx edx esi edi
  311.  
  312.  
  313.  
  314. xmpSetVolume: (xmpSetVolume_)
  315. ------------------------------------------------------------------------------
  316.   void xmpSetVolume(unsigned char vol);
  317.  
  318.   Set the relative volume.
  319.  
  320.   vol: (al)
  321.     range 0 to 64.
  322.  
  323.   modifies: nothing
  324.  
  325.  
  326.  
  327. xmpGetSync: (xmpGetSync_)
  328. ------------------------------------------------------------------------------
  329.   unsigned char xmpGetSync();
  330.  
  331.   Returns the currently set syncvalue. You set the syncvalue with the command
  332.     EFx or Sxx. I do not really know how you usually do syncronisation, but
  333.     this might help. :)
  334.  
  335.   returnvalue: (al)
  336.     the syncvalue
  337.  
  338.   modifies: al
  339.  
  340.  
  341.  
  342. xmpGetPos: (xmpGetPos_)
  343. ------------------------------------------------------------------------------
  344.   unsigned short xmpGetPos();
  345.  
  346.   Returns the current position in the song.
  347.  
  348.   returnvalue: (ax)
  349.     highbyte: current order
  350.      lowbyte: current row
  351.  
  352.   modifies: ax
  353.  
  354.  
  355.  
  356. xmpGetTimer: (xmpGetTimer_)
  357. ------------------------------------------------------------------------------
  358.   long xmpGetTimer();
  359.  
  360.   Returns the timer value. This values starts at the first tick of the
  361.   module and counts up all the time at a rate of 1193046Hz.
  362.  
  363.   returns: (eax)
  364.     the number of timer ticks since the first tick of the module.
  365.  
  366.   modifies: eax
  367.  
  368.  
  369.  
  370. xmpGetGUSPort: (xmpGetGUSPort_)
  371. ------------------------------------------------------------------------------
  372.   unsigned long xmpGetGUSPort(void *envptr);
  373.  
  374.   Reads the port of the GUS from the environment, or 0 if none is found.
  375.  
  376.   envptr: (edi)
  377.     pointer to the environment segment. if 0 the function returns 0.
  378.  
  379.   returns: (eax)
  380.     gus port
  381.  
  382.   modifies: eax ecx edi
  383.  
  384.  
  385.  
  386. xmpGetEnvPtrDPMI: (xmpGetEnvPtrDPMI_)
  387. ------------------------------------------------------------------------------
  388.   void *xmpGetEnvPtrDPMI(unsigned long psp);
  389.  
  390.   Gets a near pointer to the environment segment from the PSP selector.
  391.  
  392.   psp: (eax)
  393.     PSP selector
  394.  
  395.   returns: (edi)
  396.     pointer to the environment or 0 if failed
  397.  
  398.   modifies: eax ebx ecx edx edi
  399.  
  400.  
  401.  
  402. xmpGetEnvPtrDOS32: (xmpGetEnvPtrDOS32_)
  403. ------------------------------------------------------------------------------
  404.   void *xmpGetEnvPtrDOS32();
  405.  
  406.   Gets a near pointer to the environment segment under DOS32 extender.
  407.  
  408.   returns: (edi)
  409.     pointer to the environment
  410.  
  411.   modifies: eax ebx ecx edx esi edi
  412.  
  413.  
  414.  
  415.  
  416.     credits / greets:
  417. ==============================================================================
  418.   -Crom / ethnica for DOS32 version.
  419.   -Eclipse for a version for their OS.
  420.   -Screamager for the tune. (Sorry, I did not ask you. I hope you do
  421.      not mind too much, but I like the tune and simply had to take it!)
  422.   -Axon / Xenon Dev. for wanting to help me with DOS32. (I did not get
  423.      further messages from you, but my email was not ok at that time...)
  424.  
  425.  
  426.  
  427.     software & copyright & versions
  428. ==============================================================================
  429.   -fasttracker II rocks, like most of Tritons prods.
  430.     tested with several xm modules
  431.   -pmode/w and pmwlite belong to Charles Sheffold and Thomas Pytel.
  432.     tested with v1.20 to v1.24
  433.   -dos4g(w) extender was done by Rational Systems and Tenberry Software.
  434.     tested with v1.95 and 1.97
  435.   -dos32 extender is brought to you by Adam Seychell.
  436.     tested with v3.3
  437.   -eos extender is something by Eclipse.
  438.     tested with v2.07
  439.   -watcom c/c++ imo is the best c/c++ around.
  440.     tested with v10.0 and v10.6
  441.   -tasm is the assembler.
  442.     tested with v3.1 and others
  443.   -pmode extender is the reason for all the Tran greets.
  444.     not tested
  445.   -gravis ultrasound is a soundcard.
  446.     tested on various ones
  447.   -pc speaker sucks
  448.     failed all tests
  449.  
  450.  
  451.  
  452.  
  453.  
  454.     contact information:
  455. ==============================================================================
  456.  
  457. snailmail:
  458.  
  459.   Niklas Beisert / pascal
  460.   Oberstrasse 84
  461.   20149 Hamburg
  462.   Germany
  463.  
  464.     Fido: Niklas Beisert@2:2437/301.44
  465. Internet: mxm@p44.nightmare.harz.de
  466.  
  467.  
  468.  
  469. == FILE_ID.DIZ ===============================================================
  470. ■ cubic tiny gus ▄▄ xm player v1.5 ■
  471.  ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ ██ ▄▄▄ ▄▄ ▄▄▄▄▄▄▄▄
  472.     ▄▄▄▄▄ ▄▄  ▄▄ ██▄▄▄  ▄▄  ▄▄▄▄▄ tm
  473.    ██     ██  ██ ██  ██ ██ ██
  474.    ██     ██  ██ ██  ██ ██ ██
  475.     ▀▀▀▀▀  ▀▀▀▀▀ ▀▀▀▀▀  ▀▀  ▀▀▀▀▀
  476.  ▀▀▀▀ tiny gus xm player  v1.5 ▀▀▀▀
  477. █                                  █
  478. █ new features:                    █
  479. █ -dos32 & eos support             █
  480. █                                  █
  481. █ -flat mode, no external functs   █
  482. █   needed. tested ok with dos4gw, █
  483. █   pmode/w, wc++, eos, dos32      █
  484. █ -supports gus & quiet (clean)    █
  485. █ -supports xm & mod               █
  486. █ -size: 5.6k, pmwlite size: 3.8k  █
  487. █ -all xm features supported       █
  488. █ -plays 99% of all effects        █
  489. █ -supplies timer, sync and volume █
  490. █   functions. autodetects gus.    █
  491. ▀                                  ▀
  492. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  493.